home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Format.java < prev    next >
Text File  |  1998-09-22  |  9KB  |  215 lines
  1. /*
  2.  * @(#)Format.java    1.15 97/02/12
  3.  *
  4.  * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
  5.  * (C) Copyright IBM Corp. 1996 - All Rights Reserved
  6.  *
  7.  * Portions copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  8.  *
  9.  *   The original version of this source code and documentation is copyrighted
  10.  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  11.  * materials are provided under terms of a License Agreement between Taligent
  12.  * and Sun. This technology is protected by multiple US and International
  13.  * patents. This notice and attribution to Taligent may not be removed.
  14.  *   Taligent is a registered trademark of Taligent, Inc.
  15.  *
  16.  * Permission to use, copy, modify, and distribute this software
  17.  * and its documentation for NON-COMMERCIAL purposes and without
  18.  * fee is hereby granted provided that this copyright notice
  19.  * appears in all copies. Please refer to the file "copyright.html"
  20.  * for further important copyright and licensing information.
  21.  *
  22.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  23.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  24.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  25.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  26.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  27.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  28.  *
  29.  */
  30.  
  31. package java.text;
  32. import java.io.Serializable;
  33.  
  34. /**
  35.  * <code>Format</code> is an abstract base class for formatting locale-sensitive
  36.  * information such as dates, messages, and numbers.
  37.  *
  38.  * <p>
  39.  * <code>Format</code> defines the programming interface for formatting
  40.  * locale-sensitive objects into <code>String</code>s (the
  41.  * <code>format</code> method) and for parsing <code>String</code>s back
  42.  * into objects (the <code>parseObject</code> method). Any <code>String</code>
  43.  * formatted by <code>format</code> is guaranteed to be parseable by
  44.  * <code>parseObject</code>.
  45.  *
  46.  * <p>
  47.  * If formatting is unsuccessful because the <code>Format</code> object
  48.  * cannot format the type of object specified, <code>format</code> throws an
  49.  * <code>IllegalArgumentException</code>. Otherwise, if there is something
  50.  * illformed about the object, <code>format</code> returns the Unicode
  51.  * replacement character <code>\\uFFFD</code>.
  52.  *
  53.  * <p>
  54.  * If there is no match when parsing,
  55.  * <code>parseObject(String)</code> throws a <code>ParseException</code>,
  56.  * and <code>parseObject(String, ParsePosition)</code> leaves the
  57.  * <code>ParsePosition</code> <code>index</code> member unchanged and
  58.  * returns <code>null</code>.
  59.  *
  60.  * <p>
  61.  * <STRONG>Subclassing:</STRONG>
  62.  * The JDK provides three concrete subclasses of <code>Format</code>--
  63.  * <code>DateFormat</code>, <code>MessageFormat</code>, and
  64.  * <code>NumberFormat</code>--for formatting dates, messages, and numbers,
  65.  * respectively.
  66.  * <p>
  67.  * Concrete subclasses <em>must</em> implement these two methods:
  68.  * <ol>
  69.  * <li> <code>format(Object obj, StringBuffer toAppendTo, FieldPosition pos)</code>
  70.  * <li> <code>parseObject (String source, ParsePosition pos)</code>
  71.  * </ol>
  72.  *
  73.  * <p>
  74.  * Most subclasses will also implement the following two methods:
  75.  * <ol>
  76.  * <li>
  77.  * <code>getInstance</code> for getting a useful format object appropriate
  78.  * for the current locale
  79.  * <li>
  80.  * <code>getInstance(Locale)</code> for getting a useful format
  81.  * object appropriate for the specified locale
  82.  * </ol>
  83.  * In addition, some subclasses may also choose to implement other
  84.  * <code>getXxxxInstance</code> methods for more specialized control. For
  85.  * example, the <code>NumberFormat</code> class provides
  86.  * <code>getPercentInstance</code> and <code>getCurrencyInstance</code>
  87.  * methods for getting specialized number formatters.
  88.  *
  89.  * <p>
  90.  * Subclasses of <code>Format</code> that allow programmers to create objects
  91.  * for locales (with <code>getInstance(Locale)</code> for example)
  92.  * must also implement the following class method:
  93.  * <blockquote>
  94.  * <pre>
  95.  * public static Locale[] getAvailableLocales()
  96.  * </pre>
  97.  * </blockquote>
  98.  *
  99.  * <p>
  100.  * And finally subclasses may define a set of constants to identify the various
  101.  * fields in the formatted output. These constants are used to create a FieldPosition
  102.  * object which identifies what information is contained in the field and its
  103.  * position in the formatted result. These constants should be named
  104.  * <code><em>item</em>_FIELD</code> where <code><em>item</em></code> identifies
  105.  * the field. For examples of these constants, see <code>ERA_FIELD</code> and its
  106.  * friends in <a href="java.text.DateFormat.html"><code>DateFormat</code></a>.
  107.  *
  108.  * @see          java.text.ParsePosition
  109.  * @see          java.text.FieldPosition
  110.  * @see          java.text.NumberFormat
  111.  * @see          java.text.DateFormat
  112.  * @see          java.text.MessageFormat
  113.  * @version      1.15 02/12/97
  114.  * @author       Mark Davis
  115.  */
  116. public abstract class Format implements Serializable, Cloneable {
  117.     /**
  118.      * Formats an object to produce a string.
  119.      * <p>Subclasses will override the StringBuffer version of format.
  120.      * @param obj    The object to format
  121.      * @return       Formatted string.
  122.      * @exception IllegalArgumentException when the Format cannot format the
  123.      * type of object.
  124.      * @see          MessageFormat
  125.      * @see java.text.Format#format
  126.      */
  127.     public final String format (Object obj) {
  128.         return format(obj, new StringBuffer(), new FieldPosition(0)).toString();
  129.     }
  130.  
  131.     /**
  132.      * Formats an object to produce a string.
  133.      * Subclasses will implement for particular object, such as:
  134.      * <pre>
  135.      * StringBuffer format (Number obj, StringBuffer toAppendTo)
  136.      * Number parse (String str)
  137.      * </pre>
  138.      * These general routines allow polymorphic parsing and
  139.      * formatting for objects such as the MessageFormat.
  140.      * @param obj    The object to format
  141.      * @param toAppendTo    where the text is to be appended
  142.      * @param status    On input: an alignment field, if desired.
  143.      * On output: the offsets of the alignment field.
  144.      * @return       the value passed in as toAppendTo (this allows chaining,
  145.      * as with StringBuffer.append())
  146.      * @exception IllegalArgumentException when the Format cannot format the
  147.      * given object.
  148.      * @see  MessageFormat
  149.      * @see java.text.FieldPosition
  150.      */
  151.     public abstract StringBuffer format(Object obj,
  152.                     StringBuffer toAppendTo,
  153.                     FieldPosition pos);
  154.  
  155.     /**
  156.      * Parses a string to produce an object.
  157.      * Subclasses will typically implement for particular object, such as:
  158.      * <pre>
  159.      *       String format (Number obj);
  160.      *       String format (long obj);
  161.      *       String format (double obj);
  162.      *       Number parse (String str);
  163.      * </pre>
  164.      * @param ParsePosition Input-Output parameter.
  165.      * <p>Before calling, set status.index to the offset you want to start
  166.      * parsing at in the source.
  167.      * After calling, status.index is the end of the text you parsed.
  168.      * If error occurs, index is unchanged.
  169.      * <p>When parsing, leading whitespace is discarded
  170.      * (with successful parse),
  171.      * while trailing whitespace is left as is.
  172.      * <p>Example:
  173.      * Parsing "_12_xy" (where _ represents a space) for a number,
  174.      * with index == 0 will result in
  175.      * the number 12, with status.index updated to 3
  176.      * (just before the second space).
  177.      * Parsing a second time will result in a ParseException
  178.      * since "xy" is not a number, and leave index at 3.
  179.      * <p>Subclasses will typically supply specific parse methods that
  180.      * return different types of values. Since methods can't overload on
  181.      * return types, these will typically be named "parse", while this
  182.      * polymorphic method will always be called parseObject.
  183.      * Any parse method that does not take a status should
  184.      * throw ParseException when no text in the required format is at
  185.      * the start position.
  186.      * @return Object parsed from string. In case of error, returns null.
  187.      * @see java.text.ParsePosition
  188.      */
  189.     public abstract Object parseObject (String source, ParsePosition status);
  190.  
  191.     /**
  192.      * Parses a string to produce an object.
  193.      *
  194.      * @exception ParseException if the specified string is invalid.
  195.      */
  196.     public Object parseObject(String source) throws ParseException {
  197.         ParsePosition status = new ParsePosition(0);
  198.         Object result = parseObject(source, status);
  199.         if (status.index == 0) {
  200.             throw new ParseException("Format.parseObject(String) failed", 0);
  201.         }
  202.         return result;
  203.     }
  204.  
  205.     public Object clone() {
  206.         try {
  207.             Format other = (Format) super.clone();
  208.             return other;
  209.         } catch (CloneNotSupportedException e) {
  210.             // will never happen
  211.             return null;
  212.         }
  213.     }
  214. }
  215.